Getting Device Descriptors

The USBGetDeviceDescriptor function returns a pointer to the device descriptor of the specified device reference.

OSStatus USBGetDeviceDescriptor (
                     USBDeviceRef *deviceRef,
                     USBDeviceDescriptor *deviceDescriptor,
                     UInt32 size);

--> deviceRef

A pointer to the allocated device reference for which you want the device descriptor.

<-- deviceDescriptor

A pointer to the device descriptor.

--> size

Size of the descriptor. If the descriptor that is returned is larger than the requested size, a kUSBOverRunErr is returned and only the first size bytes of the descriptor are filled in.

Getting Interface Descriptors

The USBGetInterfaceDescriptor function returns a pointer to the interface descriptor of supplied device reference.

OSStatus USBGetInterfaceDescriptor (
                     USBInterfaceRef *interfaceRef,
                     USBInterfaceDescriptor *InterfaceDescriptor,
                     UInt32 size);

--> interfaceRef

A pointer to the allocated interface reference for which you want the interface descriptor.

<-- interfaceDescriptor

A pointer to the device interface descriptor.

--> size

Size of the descriptor. If the descriptor that is returned is larger than the requested size, a kUSBOverRunErr is returned and only the first size bytes of the descriptor are filled in.

Finding The Driver For A Device By Class

The USBGetNextDeviceByClass function returns a class driver reference for the class driver matching the specified device class and optionally the device subclass for that device.

OSStatus USBGetNextDeviceByClass (

                         USBDeviceRef *deviceRef,
                         CFragConnectionID *connID,
                         UInt16 deviceClass,
                         UInt16 deviceSubClass,
                         UInt16 deviceProtocol);

<--> deviceRef

A pointer to the device driver reference for the device class specified.

<-- connID

A pointer to the device connection ID.

--> deviceClass

A number representing the device class for which you want a compatible class driver. You can pass in kUSBAnyClass as a wildcard value. See the USB Specification for the device class descriptions and identifiers.

--> deviceSubClass

A number representing the device sub class for which you want a compatible class driver. You can pass in kUSBAnySubClass as a wildcard value. See the USB Specification for the device subclass descriptions and identifiers.

--> deviceProtocol

A number representing the device protocol for which you want a compatible class driver. You can pass in kUSBAnyProtocol as a wildcard value. See the USB Specification for the device protocol descriptions and identifiers.

The USBGetNextDeviceByClass function returns a pointer to the next usbDeviceRef for a class driver matching the specified deviceClass and (optionally) deviceSubClass and deviceProtocol parameters. Pass kNoDeviceRef for the deviceRef parameter to begin, then pass the returned device reference for subsequent searches.

An OSStatus error of -43 is returned if a device cannot be found with the specified parameters. The device reference, deviceRef, returns unchanged if no subsequent match is made. The typical way to find all similar devices is to keep calling the USBGetNextDeviceByClass function until the status value changes from noErr . At that point, the deviceRef is officially undefined.

The driver descriptor structure must have the same class and subclass codes as the codes for the device that is specified in the function call. This is particularly important for vendor specific devices, since the correct driver for the device would not typically load if the class and subclass codes don't match those for the device.

If you are developing a device and the USBGetNextDeviceByClass function isn't finding the requested device, be sure that the driver descriptor structure for your device driver has the same class and subclass codes as the device.

Constants are defined for the device class, subclass, protocol, vendor, and product identifiers which you can pass as wildcard values in the functions USBGetNextDeviceByClass and USBInstallDeviceNotification in Installing The Device Callback Request .

Constant	Value	Description
kUSBAnyClass	0xffff	Pass in as a wildcard in the deviceClass parameter or usbClass field in the device notification parameter block.
kUSBAnySubClass	0xffff	Pass in as a wildcard in the deviceSubClass parameter or usbSubClass field in the device notification parameter block
kUSBAnyProtocol	0xffff	Pass in as a wildcard in the deviceProtocol parameter or usbProtocol field in the device notification parameter block
kUSBAnyVendor	0xffff	Pass in as a wildcard in the usbVendor field in the device notification parameter block.
kUSBAnyClass	0xffff	Pass in as a wildcard in the usbProduct field in the device notification parameter block

Note

In USB version 1.0.1 (the iMac update 1.0) a bug prevented correct searches if usbClass, usbSubclass, and usbProtocol were equal 0 and kNoDeviceRef is used for the deviceRef . This behavior is not present in version 1.1 and greater of the Mac OS USB software.